%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% $Id$
%
% Documentation file for the BYU-LANL Triple Modular Redundancy (BL-TMR) Tool.
%
% Author: Brian Pratt <brianpratt@byu.net>
%         James Carroll <jcarroll@byu.net>
%         Jonathan Johnson <jonjohn@byu.net>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[english]{article}
%\usepackage[T1]{fontenc}
\usepackage{fullpage}
\usepackage{amsmath}
\usepackage{epsfig}
\usepackage{graphicx}
\usepackage{verbatim}
\usepackage{moreverb}
\numberwithin{figure}{section}
%\usepackage[latin1]{inputenc}
\IfFileExists{url.sty}{\usepackage{url}}
                      {\newcommand{\url}{\texttt}}
% use this instead of pdfgraphcompat
% Check for PDFLaTeX
\newif\ifpdf 
\ifx\pdfoutput\undefined 
   \pdffalse % we are not running PDFLaTeX 
\else
   \pdfoutput=1 % we are running PDFLaTeX 
   \pdftrue 
\fi


% This processes the file using the 'hyperref.sty' package when
% PDFLaTeX is used.  This adds internal hyperlinks throughout the
% document in the generated PDF.
\ifpdf
   \usepackage[colorlinks={true},
     urlcolor=rltblue,       % \href{...}{...} external (URL)
     filecolor=rltgreen,     % \href{...} local file
     linkcolor=rltred,       % \ref{...} and \pageref{...}
     pdftitle={BYU-LANL Triple Modular Redundancy Usage Guide Version 0.5.2 -
     30 September, 2009}, % pdfauthor={BYU Configurable Computing Lab},%
     pdfproducer={pdfLaTeX},%
     %pdfadjustspacing=1,
     pdftex]{hyperref}
\fi

% Define colors used by hyperref
\usepackage{color}
\definecolor{rltred}{rgb}{0.75,0,0}
\definecolor{rltgreen}{rgb}{0,0.5,0}
\definecolor{rltblue}{rgb}{0,0,0.75}


\vfuzz2pt % Don't report over-full v-boxes if over-edge is small
\hfuzz2pt % Don't report over-full h-boxes if over-edge is small

% 1: label, 2: path, 3: filename except extension (minus .png or .eps), 4: caption
\newcommand\figurecaption[4]{
\begin{figure}[ht]
  \centering
  \includegraphics[width=1.0\linewidth]{#2/#3}
  \parbox{1.0\linewidth}{\caption{\label{#1}#4}}
\end{figure}
}

\makeatletter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
%% Bold symbol macro for standard LaTeX users
\providecommand{\boldsymbol}[1]{\mbox{\boldmath $#1$}}

\usepackage{babel}
\makeatother

\title{BYU-LANL Triple Modular Redundancy \\ Usage Guide \\ Version 0.5.2 }
  
\author{Brigham Young University \\ Configurable Computing Lab}

\date{\today}

\begin{document}

\maketitle

\newpage
\tableofcontents
\newpage

\section{Toolflow Illustration}
\includegraphics[scale=0.7]{tool_flow.pdf}
\newpage


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Introduction}
The BYU-LANL Triple Modular Redundancy (BL-TMR) Tool is an EDIF-based
tool to insert redundancy in an FPGA design in order to increase
reliability. Triple modular redundancy (TMR) and/or duplication with
compare (DWC) are applied to an EDIF input file according to the
options chosen by the user. Partial replication focuses on ``persistent''
components of the design in order to get the ``most bang for your buck.''

The tool is also capable of inserting detectors for doing error detection using
DWC. Single- and dual-rail error detectors can be inserted in both triplicated
and duplicated designs. Special persistence detectors can be inserted in order
to give the ability to classify detected errors as persistent or non-persistent.

\section{Replication Toolflow}
The tool is split into several subtools. This allows the user to
adjust various command-line options in one phase, and then move onto
the next phase. Some phases such as JEdifNMRSelection are designed to be run in
passes in order to obtain the desired results. For example, in order to mix
duplication and triplication in a design, you can run JEdifNMRSelection twice,
once to select partitions to triplicate, and once more to select partitions to
duplicate.

\subsection{JEdifBuild}
JEdifBuild creates merged netlists in a .jedif file format from
multiple .edf files. By default, JEdifBuild also flattens the design
and optionally performs FMAP removal, RLOC removal, SRL replacement,
and half-latch removal (functions performed by JEdifSterilize in
previous versions of the toolflow). The .jedif file format is an
intermediate file format used by the remainder of the replication
tools.

\subsection{JEdifAnalyze}
JEdifAnalyze performs some basic circuit analysis necessary for
subsequent executables. In particular, it performs feedback and IOB
analysis. The results of JEdifAnalyze are saved in a circuit
description file (.cdesc) required by later executables.

\subsection{JEdifNMRSelection}
JEdifNMRSelection determines which parts of a design will be
replicated. This executable can be run in multiple passes to select
different parts of a design for different kinds of replication. Each
run of JEdifNMRSelection can select portions of a design for a single
replication type (i.e. duplication, triplication). Design portions can
be selected for replication based on available space or specific cell
types, instances, ports, and clock domains specified by the user. The
results of JEdifNMRSelection are saved in a replication description
(.rdesc) file. This file can be modified by subsequent runs of this
and other executables in the toolflow.

\subsection{JEdifVoterSelection}
JEdifVoterSelection determines the locations where voters will be
inserted into a triplicated design (or triplicated portions of a
design). Voter locations are determined using a feedback cutset
algorithm and rules for voting where downscaling is necessary. The
results are added into the replication description (.rdesc) file.

\subsection{JEdifMoreFrequentVoting}
\emph{Optional:} JEdifMoreFrequentVoting inserts extra voters for more frequent voting within a design based on a logic levels threshold or a total number of desired
partitions.

\subsection{JEdifDetectionSelection}
\emph{Optional:}
JEdifDetectionSelection determines detector locations for both triplicated and
duplicated design portions using user-specified options. Like
JEdifNMRSelection, this tool is designed to be run in multiple passes
(only one replication type can be processed per pass). Results are
saved in the replication description file (.rdesc).

\subsection{JEdifPersistenceDetection}
\emph{Optional:} JEdifPersistenceDetection determines additional
detector locations necessary for classifying persistent/non-persistent
errors detected in a design. It is designed to be run in multiple
passes. Results are saved in the replication description (.rdesc) file.

\subsection{JEdifNMR}
JEdifNMR performs the replication selected by previously run
tools. Information about what to replicate and where to insert
voters/detectors is obtained from the replication description (.rdesc)
file created by the previous steps.

\subsection{Other JEdif tools}

\subsubsection{JEdifNetList}
JEdifNetlist converts a netlist in .jedif format to EDIF (.edf) format for use
with other standard EDIF tools.

\subsubsection{JEdifQuery}
JEdifQuery is a tool used to query the contents of a .jedif file and
to provide summary information about the EDIF design contained within.

\subsubsection{JEdifReplicationQuery}
JEdifReplicationQuery is a tool used to query the contents of a
replication description file (.rdesc) and provide summary information
about the kind of replication that will be performed on a design. It
reports information about replication types, organs to be inserted
(i.e. voters, detectors), and detection error outputs.

\subsubsection{JEdifClockDomain} 
The JEdifClockDomain tool is a .jedif based tool to analyze FPGA
designs to obtain information about the clock(s). The tool first
identifies all clocks in a design. This information is then used to
optionally display other information, such as classifying Xilinx
primitives into one or more domains, showing clock crossings, etc.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\input{Build}
\newpage
\input{Analyze}
\newpage
\input{NMRSelection}
\newpage
\input{VoterSelection}
\newpage
\input{MoreFrequentVoting}
\newpage
\input{DetectionSelection}
\newpage
\input{PersistenceDetection}
\newpage
\input{NMR}
\newpage
\input{Netlist}
\newpage
\input{Query}
\newpage
\input{ReplicationQuery}
\newpage
\input{ClockDomain}
\newpage

\input{PreMitigation}

\input{Examples}
\newpage
\section{Sample Makefile for TMR}
\verbatimtabinput{makefile_tmr}
\newpage
\section{Sample Makefile for DWC}
\verbatimtabinput{makefile_dwc}
\newpage
\section{Sample Makefile for mixed TMR/DWC}
\verbatimtabinput{makefile_tmr_dwc}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newpage
\section{Special Notes}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Naming Conventions}
\label{naming conventions}
The BL-TMR tool alters the names of replicated signals, cell instances, and 
ports. Be aware of this when using placement (or other) constraints. An output
port named \texttt{myOutport} in the original EDIF file, when triplicated,
would become \texttt{myOutport\_TMR\_0}, \texttt{myOutport\_TMR\_1}, and
\texttt{myOutport\_TMR\_2}. When duplicated, the output port would become
\texttt{myOutport\_DWC\_0} and \texttt{myOutport\_DWC\_1}. Similarly, a
flip-flop whose instance name is \texttt{myFF} in the original file, when
triplicated, would become \texttt{myFF\_TMR\_0}, \texttt{myFF\_TMR\_1}, and
\texttt{myFF\_TMR\_2}. When duplicated, the instance would become
\texttt{myFF\_DWC\_0} and \texttt{myFF\_DWC\_1}. Net names follow the same
convention.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsection{Allocating More Memory for the JVM}
Larger designs may require more heap memory than the Java Virtual Machine (JVM) 
is allocated by default. Use the \texttt{-Xmx}
\footnote{See 
\url{http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/java.html\#Xms} 
for more information about this and other command-line options to the JVM.} 
option with the Java executable to change the maximum amount of memory for 
the virtual machine. The following example allocates up to 256 MB of 
heap space for the JVM:

\begin{verbatim}
> java -Xmx256M byucc.edif.tools.tmr.FlattenTMR ...
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Change Log}

{\footnotesize
\verbatiminput{../CHANGE_LOG.txt}
}
\end{document}

%
% Words to be ignored by the spell-checker:
%

% LocalWords:  BYU LANL BL-TMR EDIF FPGA TMR OBUF IBUF BUFG IBUFG LUTs
% LocalWords:  SCC SCCs FFs UCF Xilinx java JHDL netlister IOB IBUFs
% LocalWords:  OBUFs logfile INOUT TMR'd tmr txt 

